Storybook for React — Args Composition and Parameters

Storybook lets us prototype components easily with various parameters.

In this article, we’ll look at how to work with args and parameters with Storybook.

Args Composition

We can combine different args together to create stories.

For example, we can write:

src/stories/Button.stories.js

import React from 'react';

import { Button } from './Button';

export default {
  title: 'Example/Button',
  component: Button,
  argTypes: {
    backgroundColor: { control: 'color' },
  },
};

const Template = (args) => <Button {...args} />;

export const Primary = Template.bind({});
Primary.args = {
  primary: true,
  label: 'Button',
};

export const Secondary = Template.bind({});
Secondary.args = {
  label: 'Button',
};

export const Large = Template.bind({});
Large.args = {
  size: 'large',
  label: 'Button',
};

export const PrimaryLarge = Template.bind({});
PrimaryLarge.args = {
  ...Primary.args,
  ...Large.args,
}

export const Small = Template.bind({});
Small.args = {
  size: 'small',
  label: 'Button',
};

to create the PrimaryLarge arg, which is created by combining the Primary and Large args into one.

Parameters

Parameters are a set of static, named metadata about a story.

It’s used to control the behavior of Storybook features and addons.

For example, we can control the background color with our own parameters.

We can write:

src/stories/Button.stories.js

import React from 'react';

import { Button } from './Button';

export default {
  title: 'Example/Button',
  component: Button,
  argTypes: {
    backgroundColor: { control: 'color' },
  },
};

const Template = (args) => <Button {...args} />;

export const Primary = Template.bind({});
Primary.args = {
  primary: true,
  label: 'Button',
};
Primary.parameters = {
  backgrounds: {
    values: [
      { name: 'red', value: '#f00' },
      { name: 'green', value: '#0f0' },
    ],
  },
};

to add the parameters we can set in our story.

With the backgrounds property, we should see a menu on the top of the screen to let us set the background color in the preview window.

values has the name and value of the choices we can choose.

Now if we click in the Primary story, we should be able to select red or green from the menu to set the background color.

Component Parameters

Also, we can add parameters component-wide.

For example, we can write:

import React from 'react';

import { Button } from './Button';

export default {
  title: 'Example/Button',
  component: Button,
  argTypes: {
    backgroundColor: { control: 'color' },
  },
  parameters: {
    backgrounds: {
      values: [
        { name: 'red', value: '#f00' },
        { name: 'green', value: '#0f0' },
      ],
    }
  }
};

to add the backgrounds menu to all stories.

Global Parameters

Parameters can also be set globally.

To do that, we add them to the .storybook/preview.js file:

export const parameters = {
  actions: { argTypesRegex: "^on[A-Z].*" },
  backgrounds: {
    values: [
      { name: 'red', value: '#f00' },
      { name: 'green', value: '#0f0' },
    ],
  },
}

We add the backgrounds menu to our parameters object that we exported.

Parameter Inheritance

When there are global, component, and story parameters, then they’re combined with the more specific ones taking precedence over the less specific ones.

So the story ones take precedence over the component ones.

And the component ones take precedence over the global ones.

Conclusion

We can compose args and add parameters to set various things to let us preview our component in Storybook.